Basic DOS Scripting

Introduction

If you haven't read the background information yet, now is the time to do it. The scripting environment for Windows httpd is complex, due to the dual environments of Windows and DOS. Also, if you haven't written CGI scripts for other systems, you'll need to get familiar with the Common Gateway Interface.

At this point I am going to assume you are familiar with CGI and the Windows/DOS scripting environment, and that you have setup the server in its "out of the box" configuration.

The standard shell that comes with Windows is the DOS command interpreter COMMAND.COM. There are some 3rd party alternatives which offer far greater capabilities. This section deals with basic CGI scripting using COMMAND.COM. Examples are used, so make sure you are reading this via your server. If you are currently reading in local file mode, and your server is running, click here to switch to reading via your server.

PLEASE: Consider 4DOS or NDOS if you insist on doing DOS CGI

A Simple Script

Let's start with a trivial example. Suppose you have a text file that you want to serve to your Web clients (this could be something on a file server that gets periodically updated in some way). We'll use config.sys. Here is a script (basex1.bat) that would do that:

set OF=%OUTPUT_FILE%
echo Content-type: text/plain >%OF%
echo.                         >>%OF%
type c:\config.sys            >>%OF%

And here is the URL that runs the script:

/cgi-bin/basex1.bat

Things to note:

The first command creates a short name for the output file, as a convenience.
The next command states the MIME content type of the stuff that follows. If the document were a GIF image or an HTML document, the content type would be "image/gif" or "text/html", respectively. For more information see CGI Script Output.
Each command that produces output for the client must be redirected to the OUTPUT_FILE, for which we created a short variable name above. The first output must create the file, so it uses the > operator. Subsequent output-producing commands must use the >> operator to append to the file.
The second command sends a mandatory blank line that separates the header from the content. Note the trailing dot on "echo".
The last command sends the file to standard output. The complete path is required. Don't depend on any "current directory" settings, as the script may be run while you are doing other things on your system. The file can be anywhere on your network, including a Unix machine that is accessible via an NFS mount, or a PC file server, or whatever.

Environment Variables

As described in the CGI Specification, the server creates a number of environment variables that your script can use. Here is a script (basex2.bat) that displays the values:

set OF=%OUTPUT_FILE%
echo Content-type: text/plain                    >%OF%
echo.                                            >>%OF%
echo SOME(!) environment variables set by httpd: >>%OF%
echo.                                            >>%OF%
echo SERVER_SOFTWARE=%SERVER_SOFTWARE%           >>%OF%
echo SERVER_NAME=%SERVER_NAME%                   >>%OF%
echo GATEWAY_INTERFACE=%GATEWAY_INTERFACE%       >>%OF%
echo SERVER_PROTOCOL=%SERVER_PROTOCOL%           >>%OF%
echo SERVER_PORT=%SERVER_PORT%                   >>%OF%
echo REQUEST_METHOD=%REQUEST_METHOD%             >>%OF%
echo HTTP_ACCEPT=%HTTP_ACCEPT%                   >>%OF%
echo --- contents ---                            >>%OF%
type %HTTP_ACCEPT%                               >>%OF%
echo ----------------                            >>%OF%
echo SCRIPT_NAME=%SCRIPT_NAME%                   >>%OF%
echo REMOTE_HOST=%REMOTE_HOST% (blank if no DNS) >>%OF%
echo REMOTE_ADDR=%REMOTE_ADDR%                   >>%OF%
echo QUERY_STRING=%QUERY_STRING% (blank if no query in URL) >>%OF%
if not %REQUEST_METHOD%==POST goto nopost
echo CONTENT_TYPE=%CONTENT_TYPE%                 >>%OF%
echo CONTENT_LENGTH=%CONTENT_LENGTH%             >>%OF%
echo CONTENT_FILE=%CONTENT_FILE%                 >>%OF%
echo --- contents ---                            >>%OF%
type %CONTENT_FILE%                              >>%OF%
echo. >>%OF%
echo ----------------                            >>%OF%
:nopost

And here are a few ways run the script and illustrate variations in the environment variables:

Simple execution:

/cgi-bin/basex2.bat

Execution with a query string:

/cgi-bin/basex2.bat?Query+here

Use a form to POST data:

Things to note:

Are you getting the message that you should get a better shell? Those redirections to %OF% would not be needed.
The HTTP_ACCEPT variable contains the DOS file path/name of a file containing the client's acceptable types. This is a deviation from the CGI spec, required on DOS. At present, few scripts make use of this. However, you might want to check that the MIME type of the document you are about to send back to the client is in the list of types acceptable to the client. Otherwise, send an HTML-formatted error message indicating that the document is indigestible to that client.
Query data follows the script path separated by a "?". Normally this is generated by an HTML "index" document, which has a field in it to enter the query or selection. The browser (e.g. Mosaic) will then append the contents of the field (URL-encoded) to the URL including the "?" separator.
The data that is POST-ed by a form is URL-encoded (see the forms documentation) and does not end in a newline. That is why the echo. is used in the example after typing out the POST data file.

Generating HTML in the standard DOS shell

It is not possible to echo angle brackets within the DOS shell COMMAND.COM. ECHO does not provide translation of > and <. This severely limits your flexibility. You cannot directly generate HTML within the standard DOS shell. Alternatives do offer the ability to send angle brackets to standard output, plus far more capabilities to do other things. Consider switching to some other shell or interpreter.

SECURITY ALERT

Don't even think of writing a script and form that lets clients execute DOS commands directly. This is possible, but very dangerous. There are other scenarios where users can do damage to your system, or get private information. The script feature of httpd can be a trap if you're not careful. For more information see Writing Secure CGI Scripts.

Writing DOS GET scripts

Return to the Scripting Overview

Robert B. Denny <rdenny@netcom.com>